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Program design and 
coding practices 
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Software designed and written for 
Endian portability, commonly referred 
to as "Endian-neutral," should be 
recompile- and- run capable. Achiev- 
ing Endian portability requires that you 
identify all necessary Endian dependen- 
cies in a program, separating and isolat- 
ing them as best you can through inter- 
faces and conventions. "Endian- aware" 
programs, on the other hand, mav have 
well- defined, Endian- specific parts that 
require some modification for Endianness 
when porting the program to a processor 
of the opposite Endian; see Figure 1. 

Endian-neutral (EN) design goals focus 
on separating Endian-neutral and Endian- 
specific parts, and minimizing the size of 
any necessary Endian- specific pan and 
any necessary modifications for porting 
from a processor of one Endian type to 
another. 

In general, Endian dependencies can 
occur when: 



• Communications and LAN software han- 
dle Endian differences between con- 
nected systems. 

• Conversion utilities allow the end user 
to import data from an opposite-Endian 
program. 

• Compilers provide compiling options 
to generate different Endian- type code 
and data. 

• Debuggers and dump utilities provide 
options for viewing data in different En- 
dian forms. 

• An instruction-set translator has to em- 
ulate the opposite Endian on a platform. 




• An application provides Endian con- 
version for data interchange. 

• ^ appIication has both a Big-endian 
(BE) and a Little-endian (LE) version of 
the same set of source code. 

• An operating system manages a pro- 
cessor's Endian- related controls if any 
exist. 7 

• Device drivers handle Endian differ- 
ences between the processor the de- 
vice driver runs on and its attached 
devices. 
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Endian-Neutral Programming 

You can follow a number of practices for 
writing source code that's portable be- 
tween BE and LE processors. Although 
the guidelines and examples I present here 
are based on C++, the principles apply to 
any language. 

Use a high-level language. Programming- 
language keywords in a language such as 
C++ allow the declaration of data types 
and aggregate data and prov ide for cor- 
rect data type conversion. Operations such 
as casting, union, and bit field allow flex- 
ibility and optimization for handling data 
but require Endian awareness to ensure 
the production of Endian-neutral code. 



High-level language constructs should be 
used for better programming consistency 
and handling of data. 

Assembly language does not offer high- 
level constructs and data type checking, 
and is more difficult for architecture-neutrai 
programming. However, using a high-level 
language is neither a necessary nor suffi- 
cient condition for making software Endian 
neutral and, in general, the EN guidelines 
covered here apply to assembly- language 
programming as weU. 

Object-oriented design and programming 
can provide a higher degree of neutrality 
than procedural programming alone be- 
cause objects hide data from direct access 
by pointers from outside the object; how- 
ever, the object class and its methods are 
still responsible for implementing Endian 
neutrality within the object's program code. 

Use data types correctly. In general* 
the same data should not be used as dif- 
ferent data types. Type conversion can 
corrupt data and introduce Endian de- 
pendencies. Different data types can have 
different byte lengths and the same data 
type may have different lengths on dif- 
ferent processors. 

A data type should be treated by exe- 
cutable program code as intended for that 
type. A multibyte-scalar integer, for in- 
stance, is treated by the processor as a 
single, indivisible data item that represents 
a numeric value. The location of bit and 
b\te subfields within a scalar is variant be- 
tween BE and LE, so treat data according 
to its data type, length, and Endian type. 
For portability, do not twiddle with the 
internal bits and bytes of multibyte- scalar 
data while dependent on their individual 
b\ie addresses. 

Organize aggregate and scalar data. 
Program code becomes Endian dependent 
when a multiple- scalar data item is treat- 
ed as aggregate data containing multiple 
pieces of data across its bytes. Multiple 
pieces of data should be organized as ag- 
gregate data using proper programming- 
language constructs such as a data struc- 
ture or data .array. The individual members 
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Figure 1: Endian-neutral design goals. 

(continued from page 44) 
of a structure may be a scalar element or 
another aggregate data element with its 
own members. 

You should be cognizant of aggregate 
data and scalar data when programming 
and treat scalars as single, indivisible, 
nonaggregate data items. Organize scalars 
as members of an aggregate data construe 
when dealing with multiple pieces of data 
in a collective manner. 

Avoid pointers within scalars. Do 
not point or index to smaller units of stor- 
age within the internal byte structure of a 
scalar. LE data is byte- reversed BE data, 
so internal byte positions are different. Do 
not address, point, or index to a byte, half- 
word, or word scalar that may exist with 



in a longer data type. For example, a short 
integer contains two byres, an integer con- 
tains two short integers, and a long inte- 
ger contains two integers. 

Accessing b>ies internal to scalar data 
through pointers and indexing is a poor 
pnictice; see Example 1. Multiple- byte data 
elements can be defined as a byte array 
such as charpl41 % which is independent 
of Endian. 

Avoid overlaying scalars. A data item 
is said to be overlaid when it has more 
than one meaning or type. Examples of 
overlaid data include using: a short inte- 
ger within a long integer; the high- order 
byte of an integer as a flag; a bit field and 
a binary value in the same integer; and a 
scalar as an array of bytes. 



A longer data type should not overL 
a shorter data type so that integers dor.' 
overlay characters or bit fields and longc 
integers don't overlay shorter integers 
Overlaying data is not the same as shar 
ing memory for mutually exclusive use b\ 
different data types. Sometimes program" 
mers overlay data to save storage, bin 
other times storage saving is not that valu- 
able and extra program code may be nec- 
essary to get at the desired piece of dau». 

Be aware of Endianness with cast- 
ing, union, and bit fields. C++ provides* 
programming constructs that may have 
side effects on data in the same or differ- 
ent Endian modes. 

Casting forces a data-type conversion 
to another type: for example, short to long 
or char to short. Pointer or reference casts 
allow a program to view a variable of one 
data type as if it were another type. Thus, 
they make program code dependent on 
the Endian mode of execution, as in Ex- 
ample 2(a), where the cast to a short 



long a « 0x01020304: ' 
char c, «p; 

p - Uhmr •) &«: // g«t up pointer to a 
c " p(2]: // c ij 0x03 in AS aooV 

and; 0x02 in LB mod* 



Example 1: Avoiding pointing and 
indexing tvitbin scalars. 
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pointer results in pointing to diffe rvnt ckita 
depending upon whether the execution 
mode is BE or LE. Regardless of Endian. 
do not cast 3 longer type to a shorter type 
because if the value does not fit in the 
smaller type, it can lead to data corrup- 
tion as a result of type conversion; see Ex- 
ample 2(b). 

Union allows different variables and data 
types to share the same memory. Don t 
use different data types concurrently in 
union, and do not use union to do type 
conversion. The actual data currently 
stored in union, its actual data type, and 
its referenced data type must be consis- 
tent. In Example 3, for instance, the array- 
name p should not be used to access data 
stored with variable a because they are 
different types (pfOJ will access the MSB 



(«) long a: 
short b; 

Uhort ♦)&«: 
5§^b^?vr: ■ J I b-0 for BE and b«l fox LB 

' •»* 

gg ctiat b: - 
J*a£b"(char) a; 

;J?U~VA Data loaa. but no Endian p rob lea 

- .... - - - 



Example 2: (a) Making program code 
depend on Endian execution mode; (b) 
data corruption due to type conversion. 



of integer a in BE mode and the LSB of 
a in LE mode. 

A bit field is a set of adjacent bits that 
allows efficient, convenient use of mem- 
ory for implementing a program's flags, 
switches, or discretes. Example 4(a) shows 
a bit field defined in an integer. Fields can 
be referenced by name, such as bitfield. b. 

If bit- field data is created with the struc- 
ture in Example 4(a) and ported to an op- 
posite Endian system, then either the or- 
der of the actual data bit fields a, b, c, pad 
in the integer must be reversed to pad, c, 
b, a for use with the same structure or the 
order of die bit fields defined within the 
structure must be reversed for use with 
the original imported integer and bit- field 
ordering; see Example 4(b). 

The reversal effect upon bit-field or- 



char c: 

union udata ( 
int a; 

char p [4];'- >- - . -.. •«•■!. 

war 1 ■ - 

uvar.a - 0x01020304': V i;... 
c - uv«r.p[l) '// c ia 0x02 in BE mode 
• . " . and 0x03 in LB soda 



Example 3: The array name p 
should not be used to access data 
stored with variable a because they 
are different types. 



dering between BE and LE is analogous 
to byte reversal between BE and LE; in 
general practice, it s simply extended down 
to the bit-field level by the "programming 
language." However, this practice cannot 
be guaranteed for ait compilers. 

Alternatively, a program can perform 
its own bitwise- logical operations to se- 
lect, set, and test bit fields by shifting and 
masking. It must not depend on byte ad- 
dress and order, however. That would 
make it Endian specific and not portable 
to an opposite-Endian platform. 

Avoid alignment complications. Data 
alignment is a general portability concern 
and, although independent of Endian, it 



(a) 

atruet ( 
unsigned a 
unsigned b 
unsigned c 
unsigned pad 

) bitfield: « 

struct ;(-. 
■7" unsigned pad " 
.. unsigned, c.:\*. 
• * unsigned* b > , 

unsigned* a ^ 
} bitfield:.: 



2 : //two bit field 
1 ; //one bit field 

3 ; // three bit field 
10 : // ten bit padding 



10 : // ten bit padding 
3 ; // three bit field 

1 • ;. // one bit field 

2 : ; //; two bir field 



Example 4: (a) Bit fields defined in 
an integer; (b) reversing the order of 
data bit fields. 
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Second, you need to have information that's not 
only in a language you understand, but in a context 
that's relevant That's why real-time, high-level 
^language debugging is our standard. Because if 
^ you cm see how your code relates to the system - 
right when an error occurred - youTl immediately 
; : - know what caused the problem. 

Finally, you need tools that will get used. We 
^rt'^^ designed easy-to-use, open 
S^^^^^rMr^. systems with verified connec- 
^J&i tions to' leading software 
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.knowing that if they work 
well together, so can you 
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*::3i&r r ^'k:^ i ■ Get started today. 

For faster insight into your software design prob- 
lems, call your local HP sales office, and ask for our 
free "Your Solution's In Sight" Kit It includes a 
product demonstration disk, a Software Designer 
, Concept brochure, and technical literature on HFs 
entire family of software 
solutions. 

~ HEWLETT* 
Orjust turn the page. \HHM PACKARD 



BAH 0«'^ ,K, ^ L 



.V 



\4 



INDIAN 



can complicate assumptions about byte 
location. A data item is "aligned" when its 
address is a multiple of its byte length. 
Thus a 2-byte short integer aligns on an 
address that is a multiple of 2; a 4- byte 
long integer aligns on an address that is a 
multiple of 4; and an 8-byte long integer 
aligns on an address that is a multiple of 
8. If the architecture requires it, compil- 
ers will align data by default. When un- 
aligned, a data item may be at a different 
location than when aligned. 

AssumprJons about alignment, byte lo- 
cation, and Endian byte order can become 
more complex, as in Example 5. When 
aligned, a padding byte may be inserted 
by the compiler after the character w c n to 
force the integer n onto a proper cvcn- 
address boundary. 

In Example 5, the pointer p may end 
up pointing to a pad byte before n if the 
data is aligned, to the most significant b)te 
of n if the data is unaligned and BE, or to 
the least significant byte of n if the data 
is unaligned and LE. 

To reduce padding for aligned data, 
avoid intermingling different data- type 
lengths by arranging data in order from 
longer to shorter types. 

The Endian Test 

An "Endian-adaptive" program queries or 
tests the processor to decide on the En- 
dian mode of its current execution so as 
to take a LE processing path or BE pro- 
cessing path at mn time. If the processor 
does not provide a means for telling soft- 




Example 5: Dependency on alignment 
and Endian mode of execution. 



ware its Endian mode, then a program test 
can be improvised, as in Example 6(a), 
which implements an "Endian test." Endi- 
an macros can be defined for reuse in a 
program, as in Example 6(b). 

Endian-adaptive code is Endian neutral 
in that the same source can be recompiled 
without change to run in the other Endi- 
an mode. Recompilation is necessary for 
a different processor instruction set as well 
as Endian type. 

As an example of how to make code 
neutral with the "Endian test," consider 
Example 7(a). This can be written using 
the macro, as in Example 7(b), or with- 
out the macro and independent of byte 
order (for this particular example), as in 
Example 7(c). This example assumes long 
is four bytes, but this is not a safe as- 
sumption for portability. An alternate im- 
plementation of this example is to declare 
long a instead as a character array al4l in 
which case a/2/ is the same data 0x03 in 
either Endian mode, as single-byte char- 
acter data has no Endianness. 

You must be careful with an adaptive 
implementation to make sure it is portable 
for BE and LE across the required pro- 
cessors and compilers. You may be able 
to implement necessary Endian- specific 
code with more-portable Endian- adaptive 
code; nevertheless, writing Endian- neutral 
code is the first step in achieving portable 
software across platforms of different En- 
dian types. 

Application Portability 

There are different ways to port a pro- 
gram to run on other processors. The most 
common is to recompile the source code 
to run on the new processor; another way 
is to translate the original binary code and 
its normative processor instruction set on 
the new processor. 

A program can be recompiled to run on 
the instruction set of a different processor 
(recompile-and-run). If the new proces- 
sor is of the opposite Endian, then the 
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Example 6: (a) Endian test program; (b) Endian macivs defined for reuse. 



^^^^(&.longVaiflx0ie20304: *....> 

t ch#r'-c.»p; • J. i.l.'jL'w *' ' 

JTielcKit.»I ids // aet. up' pointer to" •-T.-'-T*'^ - - . V.7 -.• . v Z 
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Example 7: Making code neutral with the Endian test. 




source code (unless it's Endian neutral* 
will need to have its Endian- specific code 
modified to run in the new Endian mode 
before recompilauon. Recompiling an ap- 
plication to another processor produces a 
new binary version of the program that 
will have to be serviced and supported. A 
given application may have different bi- 
nary versions for running on different pro- 
cessors and in different Endian modes. The 
application's source-code set, any Endian- 
specific parts, and all binary versions of it 
will have to be maintained. 

Translation of binary code requires an 
instruction- set translator (1ST) to trans- 
late the original processor's instruction 
set and Endian mode on the new (non- 
native) processor. Compiled, binary code 
undergoing translation is treated as data 
by the 1ST. If the new processor is of the 
opposite Endian then the 1ST, running 
in the Endian mode of the new proces- 
sor, must handle the byte- reversed in- 
structions and data of the program be- 
ing translated. 

A special consideration is a bi-endian 
processor. A single binary version of an 
Endian- neutral program cannot run in 
both the BE and LE modes of a bi-endian 
processor even though the instruction set 
is the same. This is because the address 
model, and therefore the (scalar) byte or- 
der, is different for both executable in- 
structions (binary code), and data. The 
benefit of a bi-endian processor is that ex- 
isting LE and BE applications and their 
operating systems can be ported to it and 
still run in their native Endian mode. An 
application must be compiled to the En- 
dian of the operating system and proces- 
sor on which it will run. 

Today's modular systems share and 
reuse software resources, so be aware of 
the Endian effect on reusable resources 
and make them Endian neutral wherever 
possible. Presentation resources (icons, 
dialogs, controls, and image bitmaps), pro- 
gram resources (pointers, integers, arrays, 
structures, and headers), and miscella- 
neous resources (device drivers, presen- 
tation drivers, objects, server -resources, 
and files) are created and passed around 
for reuse in different programs and on dif- 
ferent platforms. These resources can in- 
troduce Endian dependencies into a pro- 
gram, so awareness, inspections, and 
testing are imperative. 

Data P Mobility 

Users of today's open, connected systems 
need the capability to interchange data 
between different systems. Data can be 
interchanged through media (diskettes, 
disk, tape, and so on) and local- and wide- 
area networks of client, server, and host 
communications. Data portability requires 
the ability io handle any difference be- 
rween the Endian type of the data being 
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ported and the Endian mode of the sys- 
tem 10 which it's bcin» ported. 

Data conversion between BE and Ui re- 
quires knowing ihe data type, length, and 
Endian type for all data elements of an ag- 
gregate data layout to be convened ( such 
as a data structure, array, file, or table). 
The conv ersion algorithm herween BE and 
LE is straightforward: Reverse the byte or- 
der of a given mu It ibyte- scalar data item. 
A prerequisite for conversion and often 
the crux of the conversion problem is 
knowing the aggregate data layout or or- 
ganization of the data to be converted. 
Data is often understood only by the ap- 
plication that creates it. 

When importing data created or pro- 
cessed by a program running on another 
platform, the data's Endian type and other 
data characteristics may need to be con- 
vened. Typically, the receiver or importer 
of the data does the conv ersion: this is 
known as "receiver- makes- right." 

Data can be readily interchanged be- 
tween the same application running on 
different platforms because an application 
understands its own daia. So a BE version 
and LE version of the same application 
running on two different platforms can 
exchange and convert data to the correct 
Endian cype of the application s resident 
platform. 



To interchange data between different 
application*. a conversion utility can be 
written that understands an application's 
data and converts it to another applica- 
tion's data format and Endian type. Data- 
file formats often become public for pop- 
ular applications. For example, different 

Endian-neutral 
design goals focus 

on separating 
Endian-neutral and 

Endian-specific 
parts 



versions of a word processor that runs on 
an IBM PS/2 (LE. Intel), Macintosh (BE, 
Motorola), and a RISC platform (bi-endian 
PowerPC) may need to import data from 
another word processor. 

A self- describing data resource can be 
created, handled, and convened by any 
program that understands the public spec- 
ification of its format and data descrip- 



tors For example, if a piece of data has 
associated descriptors for its data type, 
length, and Endian cype, then it can be 
easily convened. 

Data can be kept in a standard ("canon- 
ical*") form for easier conversion. For ex- 
ample, if a program always writes its data 
as LE. then a program running on a BE 
platform knows to conven that data from 
LE to BE upon reading the data from some 
magnetic/optical media, network, or com- 
munications link. 

Text Data and Unicode 

A text stream or binary stream is com- 
posed of byte data. A byte is the smallest 
addressable unit of storage; therefore, char- 
acter data has no Endianness and is neu- 
tral and ponable. This is for single- byte 
character encodings handled by die char- 
acter data types (signed and unsigned). 

The Unicode standard defines a fixed- 
width, uniform- text, character-encoding 
scheme. Ail Unicode characters are rep- 
resented as 36- bit values. For example, 
the hex value 0x0041 represents letter A; 
0x0020 ? the space character and OxO-409. 
the character named "CYRILLIC CAPITAL 
LETTER LJE. " Unicode values must be 
treated as single, 16- bit, unsigned integer 
values. Like other multibyte- scalar values. 
Unicode data stored as binarv data in a 
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Looking at information one piece at a 
time can send you down a lot of blind 
alleys. That got us thinking. What if an 
emulator could help you go straight to 
the answer? 

With dual-ported emulation memory and 
a choice of foreground or background 
monitors, you could make measurements 
in real-time - without interrupting your 
design process. 

If you could do high-level C/C++ dynamic 
debug and analysis, you'd spend less time 
deciphering code. 

Common debugger interfaces would 
make sharing data with your team easier. 
And if you could get all this on an em- 
ulator for virtually any processor you 
have, your problems would be solved. 

If that sounds like a faster approach to 

you. call one of the numbers listed below 

or your nearest HH sales office, and ask 

for a free demonstration disk. / ^ 

There is a better way* 
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(continued from [kiiu- / f " 
file, or other interchange media. i> 1 Juli- 
an dependent. To manage I nio>de data 
correctly, dan- interchange progmms musi 
be sensitive to the Endianness of UK- 
source and target platforms. 

To help deal with Enciun enn version, 
the Unicode standard describes an op- 
tional technique for programs that ma- 
nipulate Unicode duta The standard de- 
fines the value OxFEFF as the character 
named "B^TE ORDER MARK" < MOM >. Ap- 
plications may use this character i<> cx- 
plicitiv announce the Endi.innc.v* of the 
data. The byte- swapped mirror im:it*c of 
the BOM, the value OxFFFE. is not a de- 
fined Unicode ciiaracter. Therefore, an ap- 
plication expecting the BOM and finding 
OxFFFE instead, knows that the Unicode 
data is not in the Endian format expect- 
ed. The application may then decide to 
perform b\ie swapping to convert the En- 
dian type or notify the user to run a con- 
version utility. 

Bit-Field Data 

Data porta bility and compiler implemen- 
tation of bit fields is another issue. With- 
in an integer or word, fields may be as- 
signed in left- to- right order by some 
compilers and right-to-left by others. The 
programmer must contend with these 



iomplic.ili<in> in addition to Kndian byte 
order \sl.ien exchanging data acros> sys- 
tems In general. u>ing a 32-!>n "word. BE 
labels bits n-Sl ix-ginning wiih the most 
significant or leftmost bit: LE labels bits 

Endian-adaptive 
code is Endian 

neutral in that the 
same source can be 
recompiled, without 
change, to run in the 
other Endian mode 



0-3 1 beginning with the least significant 
or rightmost bit. 

A bit field is a contiguous set of bits, 
where the most significant bit :s on tlie 
left end and the least significant bit is on 
the right end. Tine programiiiing language, 
if it supports bit fields, will generally ex- 
tend the Endian type for compiled data 
down to the bit- field level, ev en if a pro- 



cessor doesn't suppon bit fields: that is. 
multiple bit fields defined within a word 
appear in left- to- right order for BE and 
right- to- left order for LE. Tliis is the pre- 
vailing practice for compilers. 

So tliree different bit fields named a.bx. 
appearing in that order and beginning at 
tlie left end of a word for BE would ap- 
pear in cJ),a order, beginning at the right 
end of a word for LE. fliis is for bit fields. 
not the bits themselves: they retain the 
same relative bit order within a defined 
field whether BE or LE. For example, if 16 
1-hn fields are defined within a ICS- bit word 
for LE, then all the bits in that word will 
in effect be in reverse order when com- 
pared to its data representation for BE. 

W hen importing bit- field data from a 
system of tlie opposite Endian rype. ei- 
ther the order of the data bit fields must 
be reversed or the bit fields must be ac- 
cessed by a program in the reverse order. 
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Debugging is a lot less complicated with 
the HP 64700 Series Emulator. But it's 
downright simple when you partner the 
emulator with development software 
from Wind River Systems. 

Tlie VxWorks^ embedded RTOS. a rich 
and fully integrated cross-development 
environment with full networking capa- 
bilities, now works side-by-side with 
HP's 64700 Debug Environment tools. 

This means you can take a Vx Works 
measurement, execute an HP analysis 
trace, and debug your real-time appli- 
cation using interfaces from both 
companies simultaneously. 

Plus you get access to Wind River s 
powerful suite of development 
tools to make your job even easier. 

Fur more information, call 
1-800-545-UTNT). And see how 
much faster embedded design 
becomes when a partnership helps 
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